home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / dggesx.z / dggesx
Encoding:
Text File  |  2002-10-03  |  12.2 KB  |  331 lines
  1.  
  2.  
  3.  
  4. DDDDGGGGGGGGEEEESSSSXXXX((((3333SSSS))))                                                          DDDDGGGGGGGGEEEESSSSXXXX((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      DGGESX - compute for a pair of N-by-N real nonsymmetric matrices (A,B),
  10.      the generalized eigenvalues, the real Schur form (S,T), and,
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE DGGESX( JOBVSL, JOBVSR, SORT, DELCTG, SENSE, N, A, LDA, B,
  14.                         LDB, SDIM, ALPHAR, ALPHAI, BETA, VSL, LDVSL, VSR,
  15.                         LDVSR, RCONDE, RCONDV, WORK, LWORK, IWORK, LIWORK,
  16.                         BWORK, INFO )
  17.  
  18.          CHARACTER      JOBVSL, JOBVSR, SENSE, SORT
  19.  
  20.          INTEGER        INFO, LDA, LDB, LDVSL, LDVSR, LIWORK, LWORK, N, SDIM
  21.  
  22.          LOGICAL        BWORK( * )
  23.  
  24.          INTEGER        IWORK( * )
  25.  
  26.          DOUBLE         PRECISION A( LDA, * ), ALPHAI( * ), ALPHAR( * ), B(
  27.                         LDB, * ), BETA( * ), RCONDE( 2 ), RCONDV( 2 ), VSL(
  28.                         LDVSL, * ), VSR( LDVSR, * ), WORK( * )
  29.  
  30.          LOGICAL        DELCTG
  31.  
  32.          EXTERNAL       DELCTG
  33.  
  34. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  35.      These routines are part of the SCSL Scientific Library and can be loaded
  36.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  37.      directs the linker to use the multi-processor version of the library.
  38.  
  39.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  40.      4 bytes (32 bits). Another version of SCSL is available in which integers
  41.      are 8 bytes (64 bits).  This version allows the user access to larger
  42.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  43.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  44.      only one of the two versions; 4-byte integer and 8-byte integer library
  45.      calls cannot be mixed.
  46.  
  47. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  48.      DGGESX computes for a pair of N-by-N real nonsymmetric matrices (A,B),
  49.      the generalized eigenvalues, the real Schur form (S,T), and, optionally,
  50.      the left and/or right matrices of Schur vectors (VSL and VSR).  This
  51.      gives the generalized Schur factorization
  52.  
  53.           (A,B) = ( (VSL) S (VSR)**T, (VSL) T (VSR)**T )
  54.  
  55.      Optionally, it also orders the eigenvalues so that a selected cluster of
  56.      eigenvalues appears in the leading diagonal blocks of the upper quasi-
  57.      triangular matrix S and the upper triangular matrix T; computes a
  58.      reciprocal condition number for the average of the selected eigenvalues
  59.      (RCONDE); and computes a reciprocal condition number for the right and
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDGGGGGGGGEEEESSSSXXXX((((3333SSSS))))                                                          DDDDGGGGGGGGEEEESSSSXXXX((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      left deflating subspaces corresponding to the selected eigenvalues
  75.      (RCONDV). The leading columns of VSL and VSR then form an orthonormal
  76.      basis for the corresponding left and right eigenspaces (deflating
  77.      subspaces).
  78.  
  79.      A generalized eigenvalue for a pair of matrices (A,B) is a scalar w or a
  80.      ratio alpha/beta = w, such that  A - w*B is singular.  It is usually
  81.      represented as the pair (alpha,beta), as there is a reasonable
  82.      interpretation for beta=0 or for both being zero.
  83.  
  84.      A pair of matrices (S,T) is in generalized real Schur form if T is upper
  85.      triangular with non-negative diagonal and S is block upper triangular
  86.      with 1-by-1 and 2-by-2 blocks.  1-by-1 blocks correspond to real
  87.      generalized eigenvalues, while 2-by-2 blocks of S will be "standardized"
  88.      by making the corresponding elements of T have the form:
  89.              [  a  0  ]
  90.              [  0  b  ]
  91.  
  92.      and the pair of corresponding 2-by-2 blocks in S and T will have a
  93.      complex conjugate pair of generalized eigenvalues.
  94.  
  95.  
  96.  
  97. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  98.      JOBVSL  (input) CHARACTER*1
  99.              = 'N':  do not compute the left Schur vectors;
  100.              = 'V':  compute the left Schur vectors.
  101.  
  102.      JOBVSR  (input) CHARACTER*1
  103.              = 'N':  do not compute the right Schur vectors;
  104.              = 'V':  compute the right Schur vectors.
  105.  
  106.      SORT    (input) CHARACTER*1
  107.              Specifies whether or not to order the eigenvalues on the diagonal
  108.              of the generalized Schur form.  = 'N':  Eigenvalues are not
  109.              ordered;
  110.              = 'S':  Eigenvalues are ordered (see DELCTG).
  111.  
  112.      DELCTG  (input) LOGICAL FUNCTION of three DOUBLE PRECISION arguments
  113.              DELCTG must be declared EXTERNAL in the calling subroutine.  If
  114.              SORT = 'N', DELCTG is not referenced.  If SORT = 'S', DELCTG is
  115.              used to select eigenvalues to sort to the top left of the Schur
  116.              form.  An eigenvalue (ALPHAR(j)+ALPHAI(j))/BETA(j) is selected if
  117.              DELCTG(ALPHAR(j),ALPHAI(j),BETA(j)) is true; i.e. if either one
  118.              of a complex conjugate pair of eigenvalues is selected, then both
  119.              complex eigenvalues are selected.  Note that a selected complex
  120.              eigenvalue may no longer satisfy
  121.              DELCTG(ALPHAR(j),ALPHAI(j),BETA(j)) = .TRUE. after ordering,
  122.              since ordering may change the value of complex eigenvalues
  123.              (especially if the eigenvalue is ill-conditioned), in this case
  124.              INFO is set to N+3.
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DDDDGGGGGGGGEEEESSSSXXXX((((3333SSSS))))                                                          DDDDGGGGGGGGEEEESSSSXXXX((((3333SSSS))))
  137.  
  138.  
  139.  
  140.      SENSE   (input) CHARACTER
  141.              Determines which reciprocal condition numbers are computed.  =
  142.              'N' : None are computed;
  143.              = 'E' : Computed for average of selected eigenvalues only;
  144.              = 'V' : Computed for selected deflating subspaces only;
  145.              = 'B' : Computed for both.  If SENSE = 'E', 'V', or 'B', SORT
  146.              must equal 'S'.
  147.  
  148.      N       (input) INTEGER
  149.              The order of the matrices A, B, VSL, and VSR.  N >= 0.
  150.  
  151.      A       (input/output) DOUBLE PRECISION array, dimension (LDA, N)
  152.              On entry, the first of the pair of matrices.  On exit, A has been
  153.              overwritten by its generalized Schur form S.
  154.  
  155.      LDA     (input) INTEGER
  156.              The leading dimension of A.  LDA >= max(1,N).
  157.  
  158.      B       (input/output) DOUBLE PRECISION array, dimension (LDB, N)
  159.              On entry, the second of the pair of matrices.  On exit, B has
  160.              been overwritten by its generalized Schur form T.
  161.  
  162.      LDB     (input) INTEGER
  163.              The leading dimension of B.  LDB >= max(1,N).
  164.  
  165.      SDIM    (output) INTEGER
  166.              If SORT = 'N', SDIM = 0.  If SORT = 'S', SDIM = number of
  167.              eigenvalues (after sorting) for which DELCTG is true.  (Complex
  168.              conjugate pairs for which DELCTG is true for either eigenvalue
  169.              count as 2.)
  170.  
  171.      ALPHAR  (output) DOUBLE PRECISION array, dimension (N)
  172.              ALPHAI  (output) DOUBLE PRECISION array, dimension (N) BETA
  173.              (output) DOUBLE PRECISION array, dimension (N) On exit,
  174.              (ALPHAR(j) + ALPHAI(j)*i)/BETA(j), j=1,...,N, will be the
  175.              generalized eigenvalues.  ALPHAR(j) + ALPHAI(j)*i and
  176.              BETA(j),j=1,...,N  are the diagonals of the complex Schur form
  177.              (S,T) that would result if the 2-by-2 diagonal blocks of the real
  178.              Schur form of (A,B) were further reduced to triangular form using
  179.              2-by-2 complex unitary transformations.  If ALPHAI(j) is zero,
  180.              then the j-th eigenvalue is real; if positive, then the j-th and
  181.              (j+1)-st eigenvalues are a complex conjugate pair, with
  182.              ALPHAI(j+1) negative.
  183.  
  184.              Note: the quotients ALPHAR(j)/BETA(j) and ALPHAI(j)/BETA(j) may
  185.              easily over- or underflow, and BETA(j) may even be zero.  Thus,
  186.              the user should avoid naively computing the ratio.  However,
  187.              ALPHAR and ALPHAI will be always less than and usually comparable
  188.              with norm(A) in magnitude, and BETA always less than and usually
  189.              comparable with norm(B).
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. DDDDGGGGGGGGEEEESSSSXXXX((((3333SSSS))))                                                          DDDDGGGGGGGGEEEESSSSXXXX((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      VSL     (output) DOUBLE PRECISION array, dimension (LDVSL,N)
  207.              If JOBVSL = 'V', VSL will contain the left Schur vectors.  Not
  208.              referenced if JOBVSL = 'N'.
  209.  
  210.      LDVSL   (input) INTEGER
  211.              The leading dimension of the matrix VSL. LDVSL >=1, and if JOBVSL
  212.              = 'V', LDVSL >= N.
  213.  
  214.      VSR     (output) DOUBLE PRECISION array, dimension (LDVSR,N)
  215.              If JOBVSR = 'V', VSR will contain the right Schur vectors.  Not
  216.              referenced if JOBVSR = 'N'.
  217.  
  218.      LDVSR   (input) INTEGER
  219.              The leading dimension of the matrix VSR. LDVSR >= 1, and if
  220.              JOBVSR = 'V', LDVSR >= N.
  221.  
  222.      RCONDE  (output) DOUBLE PRECISION array, dimension ( 2 )
  223.              If SENSE = 'E' or 'B', RCONDE(1) and RCONDE(2) contain the
  224.              reciprocal condition numbers for the average of the selected
  225.              eigenvalues.  Not referenced if SENSE = 'N' or 'V'.
  226.  
  227.      RCONDV  (output) DOUBLE PRECISION array, dimension ( 2 )
  228.              If SENSE = 'V' or 'B', RCONDV(1) and RCONDV(2) contain the
  229.              reciprocal condition numbers for the selected deflating
  230.              subspaces.  Not referenced if SENSE = 'N' or 'E'.
  231.  
  232.      WORK    (workspace/output) DOUBLE PRECISION array, dimension (LWORK)
  233.              On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  234.  
  235.      LWORK   (input) INTEGER
  236.              The dimension of the array WORK.  LWORK >= 8*(N+1)+16.  If SENSE
  237.              = 'E', 'V', or 'B', LWORK >= MAX( 8*(N+1)+16, 2*SDIM*(N-SDIM) ).
  238.  
  239.      IWORK   (workspace) INTEGER array, dimension (LIWORK)
  240.              Not referenced if SENSE = 'N'.
  241.  
  242.      LIWORK  (input) INTEGER
  243.              The dimension of the array WORK.  LIWORK >= N+6.
  244.  
  245.      BWORK   (workspace) LOGICAL array, dimension (N)
  246.              Not referenced if SORT = 'N'.
  247.  
  248.      INFO    (output) INTEGER
  249.              = 0:  successful exit
  250.              < 0:  if INFO = -i, the i-th argument had an illegal value.
  251.              = 1,...,N:  The QZ iteration failed.  (A,B) are not in Schur
  252.              form, but ALPHAR(j), ALPHAI(j), and BETA(j) should be correct for
  253.              j=INFO+1,...,N.  > N:  =N+1: other than QZ iteration failed in
  254.              DHGEQZ
  255.              =N+2: after reordering, roundoff changed values of some complex
  256.              eigenvalues so that leading eigenvalues in the Generalized Schur
  257.              form no longer satisfy DELCTG=.TRUE.  This could also be caused
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. DDDDGGGGGGGGEEEESSSSXXXX((((3333SSSS))))                                                          DDDDGGGGGGGGEEEESSSSXXXX((((3333SSSS))))
  269.  
  270.  
  271.  
  272.              due to scaling.  =N+3: reordering failed in DTGSEN.
  273.  
  274.              Further details ===============
  275.  
  276.              An approximate (asymptotic) bound on the average absolute error
  277.              of the selected eigenvalues is
  278.  
  279.              EPS * norm((A, B)) / RCONDE( 1 ).
  280.  
  281.              An approximate (asymptotic) bound on the maximum angular error in
  282.              the computed deflating subspaces is
  283.  
  284.              EPS * norm((A, B)) / RCONDV( 2 ).
  285.  
  286.              See LAPACK User's Guide, section 4.11 for more information.
  287.  
  288. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  289.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  290.  
  291.      This man page is available only online.
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.